{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6f0faff3-7b67-420b-87db-8dfbe4acad2e",
   "metadata": {},
   "source": [
    "# Geographic Paths and Labels\n",
    "\n",
    "A geographic plot connecting two locations using `paths()` and `labels()`. This example demonstrates how to compose map-based annotations.\n",
    "\n",
    "Notice how the line in blue between New York and Delhi is not straight on a flat `PlateCarree` map, this is because the `Geodetic` coordinate system is a truly spherical coordinate system, where a line between two points is defined as the shortest path between those points on the globe rather than 2d Cartesian space."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0667e6a0-b9aa-4277-abc2-f3bceabaf2fb",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import hvplot.pandas  # noqa\n",
    "import cartopy.crs as ccrs\n",
    "\n",
    "df = pd.DataFrame({\n",
    "    'city': ['New York', 'Delhi'],\n",
    "    'lon': [-74.006, 77.1025],\n",
    "    'lat': [40.7128, 28.7041]\n",
    "})\n",
    "\n",
    "# Shared plot args\n",
    "common_kwargs = dict(\n",
    "    x='lon', y='lat', geo=True,\n",
    "    projection=ccrs.PlateCarree(), global_extent=True,\n",
    ")\n",
    "\n",
    "# Create paths, points, and labels\n",
    "shortest_path = df.hvplot.paths(\n",
    "    color='blue', crs=ccrs.Geodetic(),\n",
    "    features=['coastline'], **common_kwargs\n",
    ")\n",
    "straight_path = df.hvplot.paths(\n",
    "    color='grey', crs=ccrs.PlateCarree(), line_dash='dashed',\n",
    "    line_width=2, **common_kwargs\n",
    ")\n",
    "points = df.hvplot.points(color='red', size=10, **common_kwargs)\n",
    "labels = df.hvplot.labels(\n",
    "    text='city', text_baseline='bottom',\n",
    "    text_color='black', text_align='left', **common_kwargs\n",
    ")\n",
    "\n",
    "# Compose the final plot\n",
    "shortest_path * straight_path * points * labels"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5eb84c15-c442-4c2f-a6af-4f5e4ef41796",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import hvplot.pandas  # noqa\n",
    "import cartopy.crs as ccrs\n",
    "hvplot.extension('matplotlib')\n",
    "\n",
    "df = pd.DataFrame({\n",
    "    'city': ['New York', 'Delhi'],\n",
    "    'lon': [-74.006, 77.1025],\n",
    "    'lat': [40.7128, 28.7041]\n",
    "})\n",
    "\n",
    "# Shared plot args\n",
    "common_kwargs = dict(\n",
    "    x='lon', y='lat', geo=True, width=700,\n",
    "    projection=ccrs.PlateCarree(), global_extent=True,\n",
    ")\n",
    "\n",
    "# Create paths, points, and labels\n",
    "shortest_path = df.hvplot.paths(\n",
    "    color='blue', crs=ccrs.Geodetic(),\n",
    "    features=['coastline'], **common_kwargs\n",
    ")\n",
    "straight_path = df.hvplot.paths(\n",
    "    color='grey', crs=ccrs.PlateCarree(),\n",
    "    linestyle='dashed', linewidth=2, **common_kwargs\n",
    ")\n",
    "points = df.hvplot.points(color='red', size=1000, **common_kwargs)\n",
    "labels = df.hvplot.labels(\n",
    "    text='city', verticalalignment='bottom', horizontalalignment='left',\n",
    "    color='black', size=300, **common_kwargs\n",
    ")\n",
    "\n",
    "# Compose the final plot\n",
    "shortest_path * straight_path * points * labels"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b04562e7-3958-423f-96d0-c3988f4c419f",
   "metadata": {},
   "source": [
    "*Example adapted from https://scitools.org.uk/cartopy/docs/latest/matplotlib/intro.html.*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a9a75b1-f129-4d93-9552-a0161f84aaf2",
   "metadata": {},
   "source": [
    ":::{seealso}\n",
    "- [Paths reference documentation](../../ref/api/manual/hvplot.hvPlot.paths.ipynb).\n",
    "- [Labels reference documentation](../../ref/api/manual/hvplot.hvPlot.labels.ipynb).\n",
    ":::"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
